Configure Calculated Attribute: Calculation Rules

The Calculation Rules tab allows you to define the expression used to derive a value for a Calculated Attribute.

The Loyalty platform offers two methods of defining the expression: 

  • Advanced : Enter a custom Groovy expression.

  • Simple: Utilize the platform's user interface to build the underlying Groovy expression.

Note: You can optionally use both methods. For example, you can build an expression using the Simple method, then switch to the Advanced method. The code editor will display the generated Groovy expression, which you can manually modify as needed.

Advanced Method

The Advanced method allows you to manually enter a Groovy expression.

  1. Navigate to the Calculation Rules tab of the Member Attribute Details screen.

  2. Select Advanced.

  3. In the code editor, enter your Groovy expression.

  4. Click Save.

Simple Method

The Simple method is intended for non-technical users, and allows you to build Calculation Rules without having to write Groovy code. Each Calculation Rule comprises a Condition (criteria to evaluate) and a Result (value to populate when the Condition evaluates to "true").

That platform evaluates each Calculation Rule in sequence from top to bottom:

  • If a Calculation Rule evaluates to "true," the Result is applied.

  • If a Calculation Rule evaluates to "false," the next Calculation Rule is evaluated.

  • If no Calculation Rules evaluate to "true," the platform uses the Default Value defined for this Member Attribute.

This screen utilizes the term Rule in two different contexts. This article uses the following terms to differentiate between the two types of Rules:

  • Calculation Rule: A combination of a Condition and a Result as described above. A Calculated Attribute can have one or more of these types of Rules. Calculation Rules use an IF-THEN-ELSE structure. For example:

    • Evaluate Rule A

    • IF Rule A is True THEN Use Result A

    • ELSE Evaluate Rule B, etc.

  • Conditional Rule: A single logical statement used within the Condition, typically comprising a data element, an operator, and a value (for example, "Tier equal to Gold"). A Condition can have one or more of these types of Rules. Multiple Conditional Rules are joined with either an AND or an OR operator.

To define the expression for a Calculated Attribute using the Simple method:

  1. Navigate to the Calculation Rules tab of the Member Attribute Details screen.

  2. Select Simple.

  3. Click Add Rule. The platform adds a new area for defining the Calculation Rule.

  1. Define the Condition(s) for the Calculation Rule (see Define a Condition below for details).

  2. Define the Result for the Calculation Rule (see Define the Result below for details).

  3. Repeat the above steps as necessary to add additional Calculation Rules.

  4. Optionally, to rearrange the sequence of Calculation Rules, click-and-drag the handle in the top-left corner of the Calculation Rule box, and drop it in its desired new location.

  5. Optionally, to delete a Calculation Rule, click the Delete link next to it.

  6. Click Save.

  7. As you define a Calculation Rule, the platform automatically generates the Groovy expression for it. To see the underlying expression for a Calculation Rule, click the Show Expression link next to it.

Note: You can also view the underlying Groovy expression for the entire Calculated Attribute (comprising all Calculation Rules) by clicking the Show Expression button.

Define a Condition

A Condition is a set of logical criteria that the platform evaluates for a Member when the Calculated Attribute is refreshed. The default Condition for a new Calculation Rule is "Always True," meaning there are no criteria to evaluate.

To define a Condition:

  1. Click the Edit icon next to Always True.

  1. Click the Add icon, then select Add Rule. The platform adds a new blank row. 

  1. The first drop-down menu is populated with all of the different object types in Loyalty that are available for use. From this drop-down menu, select one of the following object types to expand it and see the available options:

This option allows you to define a logical statement based on a value in a Member Attribute.

  1. From the menu, select the desired Member Attribute.

  2. Select a mathematical operator; the available operators will vary based on the Data Type of the item you selected above. 

  3. Enter or select a value. 

This option allows you to define a logical statement based on a value in a Member Preference.

  1. From the menu, select the desired Member Preference.

  2. Select a mathematical operator. 

  3. Enter or select a value. 

This option allows you to define a logical statement by performing a mathematical calculation on a selected Activity Type.

  1. From the menu, select the desired calculation method: Aggregate, Count, or Recency.

  2. From the second drop-down menu, select the desired Activity Type.

  3. Select a mathematical operator. 

  4. Enter or select a value. 

  5. Based on the selected calculation method, the platform provides the option to enter additional criteria:

    • Count: Define a time period, such as "Is In Last 3 Months." The use of a time period is optional, but recommended to improve system performance.

    • Aggregate: Select how to perform the aggregation: either by picking an Attribute on which to aggregate, or by entering a Groovy expression. Select the Aggregate Function: Sum, Minimum, or Maximum. Define a time period, such as "Is In Last 3 Months." The use of a time period is optional, but recommended to improve system performance.

This option allows you to define a logical statement using a Member's history of Metric usage.

  1. From the menu, select the desired usage type: Balance, Earn, Expire, or Redeem.

  2. From the second drop-down menu, select the desired Metric.

  3. Select a mathematical operator. 

  4. Enter or select a value. 

  5. For the Earn, Expire, and Redeem Metric usage types, define a time period, such as "Is In Last 3 Months." The use of a time period is optional, but recommended to improve system performance.

This option allows you to define a logical statement by referencing either a Lookup table or a Member Function.

  1. From the menu, select either Lookup or Function.

  2. From the second drop-down menu, select the desired Lookup table or Member Function.

  3. Select a mathematical operator. 

  4. Enter or select a value. 

  5. If you selected a Lookup table and it has Parameters defined, select the Attribute on which to match.

  6. If you selected a Member Function and it has Arguments defined, select the Attribute on which to match.

This option allows you to define a logical statement using a variable defined on the Variables tab. For more information, please see Configure a Calculated Attribute: Variables.

  1. From the menu, select the desired variable.

  2. Select a mathematical operator. 

  3. Enter or select a value. 

 

  1. Repeat the above steps as needed to define more Conditional Rules.

  2. Optionally, to remove a Conditional Rule, click the Remove icon next to it.

  3. Once you define more than one Conditional Rule, select the logical operator. From the Include customers that meet drop-down menu, select either: 

    • All of the following: Use an 'AND' operator such that all Conditional Rules must be true for the Calculation Rule to evaluate to "true."

    • Some of the following: Use an 'OR' operator such that at least one of the Conditional Rules must be true for the Calculation Rule to evaluate to "true." 

  4. Optionally, you can also organize Conditional Rules into Rule Groups. A Rule Group allows you to build more complex logical criteria. To create a Rule Group, click the Add icon, then select Add Rule Group. The platform creates a Group, which is represented visually as a nested box with its own operator and Add icon. Within this Group box, click the Add icon to define the Conditional Rule (or Rules) using the same process as described above. Use the toggle within the Group box to define the logical operator.

Note: By clicking the Group button inside the Group box, you can create "nested" groups.

  1. Click Save.

Define the Result

When a Condition evaluates to true for a Member, the Result determines the value assigned to the Calculated Attribute. The platform provides the following options for defining the Result:

This option allows you to define the result as a static value.

  1. In the Result field, enter the desired value. 

Note: The Result value must conform to the Data Type defined for the Calculated Attribute. For example, if the Calculated Attribute is an Integer, you can't enter letters into he Result field.

This option allows you to define the result using a Groovy script.

  1. In the code editor, enter the desired Groovy script. 

This option allows you to define numerical ranges, or "buckets," into which Member records will get grouped. You can select a Member Attribute on which to group, or perform a calculation on a Metric.

  1. From the Bin Based On drop-down menu, select either a Member Attribute or a Metric usage type. 

  1. If you selected the Earn, Expire, or Redeem Metric usage types, define a time period, such as "Is In Last 3 Months." The use of a time period is optional, but recommended to improve system performance.

  2. If you selected a Metric usage type, from the Metric drop-down menu, select the desired Metric.

The bins, or buckets, are defined using a spreadsheet style grid, where each row in the grid represents a bin. For each bin, you must define the start and end of the numeric range (start / end values are inclusive), and the Result.

  1. In the first row in the Result column, enter the Result value for the first bin.

  2. In the Range Start column, enter the start of the range for this bin.

  3. In the Range End column, enter the end of the range for this bin.

  4. To define additional bins, click Result. The platform adds a new blank row in the grid. Repeat the above steps to define the Result, start value, and end value.

This option allows you to define the result by performing a mathematical calculation on a selected Activity Type.

  1. From the Activity Type drop-down menu, search for and select an Activity Type.

  2. Define a time period, such as "Is In Last 3 Months." The use of a time period is optional, but recommended to improve system performance.

  3. From the Aggregate Type drop-down menu, select the mathematical function. Currently the only supported option is Sum.

  4. Select how to perform the aggregation: either by picking an Attribute on which to aggregate, or by entering a Groovy expression.

The Filter section lets you optionally define logical conditions that limit the records that get included in the aggregation. To define a Filter:

  1. Click the Add icon, then select Add Rule. The platform adds a new blank row. 

  2. The first drop-down menu is populated with all of the different object types in Loyalty that are available for use. From this drop-down menu, select one of the following object types to expand it and see the available options:

This option lets you define a logical statement based on a value in an Activity Attribute.

  1. From the menu, select the desired Activity Attribute.

  2. Select a mathematical operator; the available operators will vary based on the Data Type of the item you selected above. 

  3. Enter or select a value. 

This option lets you define a logical statement based on a value in an Line Item Activity Attribute. This option is displayed only if the Activity Type you selected above has Line Items.

  1. From the menu, select the desired Activity Line Item Attribute.

  2. Select a mathematical operator; the available operators will vary based on the Data Type of the item you selected above. 

  3. Enter or select a value. 

 

  1. Repeat the above steps as needed to define more Rules. Optionally, to remove a Rule, click the Remove icon next to it.

  2. Optionally, you can also organize Rules into Rule Groups. A Rule Group allows you to build more complex selection criteria. To create a Rule Group, click the Add icon, then select Add Rule Group. The platform creates a Group, which is represented visually as a nested box with its own operator and Add icon. Within this Group box, click the Add icon to define the Rule (or Rules) using the same process as described above. Use the toggle within the Group box to define the logical operator for the Rules within the Group.

Note: By clicking the Group button inside the Group box, you can create "nested" groups.

This option allows you to define the result using a decision table. A decision table is a spreadsheet style grid, where:

  • Each row in the grid represents a possible Result.

  • Each column in the grid represent a condition that must be met in order for that row's Result to be used. The condition is defined using a simple logical statement based on a value in a Member Attribute. Multiple columns are joined with an AND operator. To instead use an OR operator, you must define a Column Group, as described below.

The platform evaluates a Member against the condition(s) defined in the first row, and if met, the Member is assigned that Result. If not, the Member is evaluated against the condition(s) defined in the second row, and so forth.

  1. To add a row to the decision table, click Add > Row. Click into the Result column, and enter the Result represented by this row.

  2. Repeat the above step as needed to define additional rows and Results in the decision table.

  3. Optionally, to add a column to the decision table, click Add > Column. The platform adds a blank column to the table.

  4. Click into the column header, and search for and select a Member Attribute.

  5. Click into the column cell in the first row, and select an operator.

  6. Click into the column cell in the first row again, and enter or select a value.

  7. Repeat the above steps to define the operator / value for this column, for every row.

  8. Optionally, to add another column, click Add > Column again, and repeat the above steps. Multiple columns are joined by an AND operator.

  9. If you need to define a condition using an OR operator, you must use a Column Group. A Column Group is a collection of one or more columns; the columns within the Group are joined by an OR operator. To add a Column Group, click Add > Column Group. The platform adds a Column Group comprising a single column. Define the condition for this column as described above. To add more columns within the group, click the Add icon within the Column Group header. You can also click into the Column Group header to give the Group a descriptive name.

  10. Optionally, to delete a row, click the Delete icon within the Result column. To delete a column, click the Delete icon within the column header. To delete an entire Column Group, click the delete icon with the Column Group header.